home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 4 / Amiga Tools 4.iso / tools / developer-tools / assembler / startup_asm35 / docs / startup_asm.doc < prev   
Encoding:
Text File  |  1996-02-26  |  15.6 KB  |  531 lines
  1.  
  2. Startup.asm
  3. ===========
  4.  
  5. $VER: Startup_asm 3.5 (7.12.95)
  6.  
  7. Copyright © 1995, by Kenneth C. Nilsen.
  8. All rights reserved.
  9.  
  10. Currently the most powerful startup code you'll find in assembler.
  11. This source is public domain.
  12.  
  13. Works with any kickstart, chip and configuration.
  14.  
  15.  
  16.  
  17. WHY USE THIS CODE?
  18. ==================
  19.  
  20.      1) It makes your programs safe from crashing on system that has lower
  21.     processor configuration than you require. An error message is given
  22.     and the program will exit without executing any of your code.
  23.      2) It prevents your program to crash if you start from Workbench/icon.
  24.      3) Expands your assembler with 10 more commands!
  25.      4) Very easy to open libraries. One line opens a library. Even error
  26.     messages are given if any of the libraries can't be opened.
  27.      5) It enables easy argument parsing where one argument is given to you
  28.     one by one.
  29.      6) Very easy to implement in your sources, just one include (itself).
  30.      7) Supports the 68060 processor (tested).
  31.      8) Source is completly safe. Contributed to the public domain by 12 years
  32.     experience with programming.
  33.      9) You don't need any external includes to make this startup code work.
  34.     10) Learn how to deal with these situation by study the source.
  35.     11) Experiment with the source and make a startup code for your needs.
  36.     12) By using the internal NextArg macro you can have more UNIX like
  37.     option command lines for your programs. The ReadArgs() function is
  38.     limited in that manner.
  39.     13) Helps you setting the right return code at exit.
  40.     14) A demo program and source are following this archive.
  41.  
  42.  
  43.  
  44. NEW FEATURES
  45. ============
  46.  
  47. 3.5:
  48.     - Optimized the code and made if more compatible with a larger range
  49.       of assemblers.
  50.  
  51.       Added macros to the macro file to support BarFly.
  52.  
  53. 3.4:
  54.     - Added <Return> macro. Use it like "Return 0" and it puts the return
  55.       code in D0 and makes a RTS automatically. Added info to doc and 
  56.       startup example. Optimized some code.
  57.  
  58.       Added comments in the Startup.asm source! :)
  59.  
  60.       Added *n (newline) feature in argument parsing. Use this like:
  61.       > Test "This is a test*nto see newline in *"qvotes*".". This will be:
  62.           > This is a test
  63.           > to see newline in "qvotes".
  64.  
  65.       Included a sample header source in the archive.
  66.  
  67.       This is the first public release on the AmiNet.
  68.  
  69. 3.3beta:
  70.     - Is now bug free! :) Only thing to change now is to read icon args/
  71.       tooltypes from Workbench due to a main release :)
  72.  
  73. 3.2beta:
  74.     - Added 68040 FPU options. Use:
  75.       MathProc = 68881/68882 or 68040 to set FPU. 0=no FPU.
  76.  
  77.  
  78.  
  79. BUG FIXES
  80. =========
  81.  
  82.  
  83. 3.3beta:
  84.     - an enforcer hit fixed (BYTE READ FROM 0). Occured when starting from
  85.       icon with no argument. Never was dangerous, but still nice to have
  86.       it all clean :)
  87.  
  88. 3.2beta:
  89.     - there was a bug testing for 68060. If you had a 040 with 040FPU this
  90.       allowed you to run programs assembled for 060.
  91.     - a bug where reported about the Version and TaskName macros. These
  92.       work fine with AsmOne, but both DevPac and Barfly can not handle
  93.       spaces between words even if they are in qvotes. Sorry, can not do
  94.       something about this (I think) so write version strings manually and
  95.       use TaskName with underscores instead of spaces...
  96.     - an enforcer hit (BYTE READ FROM 0) where reported when started from
  97.       workbench. Working on the problem, but no danger... :)
  98.  
  99. 3.1beta:
  100.     - Implemented an unfinished Startup.asm file in the 3.0 archive.
  101.     - Expanded the NextArg macro to solve *" situations in arguments.
  102.     - Added buffercount for output strings. This caused misunderstandings
  103.       and people reported bugs. Not a bug, but not a good presentation :)
  104.  
  105. (thanks to Eivind Olsen for reporting these bugs :) )
  106.  
  107.  
  108.  
  109. DOCUMENT OVERVIEW
  110. =================
  111.  
  112. Pre:    - Why use this code?
  113.     - New features
  114.     - Bug fixes
  115.     - Document overview
  116.  
  117.     - What is this?
  118.     - How to use "Startup.asm"
  119.     - Helping macros
  120.     - Parsing arguments
  121.     - Sections
  122.     - Extras
  123.     - Summary
  124.     - Trouble shooting
  125.     - Address
  126.     - Source header example
  127.  
  128.  
  129.  
  130. WHAT IS THIS?
  131. =============
  132.  
  133. For those of you who programs a lot this is a powerful aid in making your
  134. programs function saftly. You don't have to think about checking processor
  135. types, you don't have to open the libraries you need yourself, you don't have
  136. to think about giving error messages and you can run your program from both
  137. Shell and WORKBENCH.
  138.  
  139. This is an include you should include first in all your sources.
  140.  
  141.  
  142. So, what's new about this startup include?
  143.  
  144.     * It opens all the libraries you need and give message if any error
  145.       occurs on ALL libraries that would not open.
  146.     * It checks the processor type for you so you wount run a 68020 program
  147.       on a 68000 etc.
  148.     * It checks your system for math-co-processor if you need that in your
  149.       program.
  150.     * Parse cli arguments one by one very easy, all done for you.
  151.     * Enable/Disable icon startup while programming (eg. from AsmOne)
  152.     * Need no includes to work.
  153.     * Name your task in a very easy way at any time.
  154.     * Easy accessing information about type of startup in your programs.
  155.     * Easy defining libraries and requirements.
  156.     * System-safe code.
  157.     * Make xRef's and you can link it to c sources as well.
  158.     * Highly optimized within legal conditions.
  159.     * Short (about 1kb assembled)
  160.  
  161. Future:
  162.  
  163.     * Read arguments from icons.
  164.     * Self detaching startup from CLI (anyone got any code for this??)
  165.     * Open devices?
  166.  
  167.  
  168.  
  169. HOW TO USE THE "Startup.asm"
  170. ============================
  171.  
  172. You need to initialize 3 global values which describing what processors you
  173. need and how to run:
  174.  
  175. 1)    "StartSkip=",
  176.  
  177.     will be =0 when your program is finished. This enables you to run
  178.     programs from icons as well as from CLI. 1 is made for those (like me)
  179.     who programs in AsmOne. If you start your program from AsmOne it will
  180.     do a WaitPort() forever. The "1" tells AsmOne to skip the WaitPort()
  181.     and enable your program to start from AsmOne. This will also work with
  182.     CLI startup, but not from WB so remember to set StartSkip to 0.
  183.  
  184. 2)    "Processor=",
  185.  
  186.     tells which processor you need. If any will do use "0" or "68000". If
  187.     you don't use 0 you must define a known processor like: 68000, 68010,
  188.     68020, 68030, 68040 or 68060. Tip: Use =0 if you only need a 68000,
  189.     this will be faster.
  190.  
  191. 3)    "MathProc=",
  192.  
  193.     will be defined if you need a FPU in your program. Initialize it with
  194.     0 if no FPU is needed, or define 68881 or 68882. If you define 68881
  195.     the 68882 will work as well. The same thing with the processor. If you
  196.     have a "processor" or higher the program will work. If you have a
  197.     68040 with an FPU, use MathProc = 68040 instead.
  198.  
  199. You can of course define these global values in the Startup.asm file if you
  200. always use the same setup or don't want the labels shown in your source.
  201.  
  202. To set a condition to kickstarts you just have to request a library version
  203. for that kickstart, eg. DefLib dos,37 will require kick. 2.0 etc. See below.
  204.  
  205. Nest step is to define the libraries you need to use. You must have the label
  206. "Init" first in your program. Do it like this:
  207.  
  208. Init    DefLib    dos,37      ;remember to use small cases with library names!
  209.     DefLib    <library wo/.library>,<version>
  210.     ...and so on...
  211.     DefEnd
  212.  
  213. This part contains 2 macros:
  214.  
  215. 1)    DefLib,
  216.  
  217.     which defines the library and the version number. If the library cannot
  218.     be opened you'll get a message about it. This is for every library you
  219.     try to open, so it will not stop at the first error. Do NOT use any
  220.     extensions, only the library name in LOWER cases.
  221.  
  222. 2)    DefEnd,
  223.  
  224.     This tells the startup code that you are finished with defining your
  225.     init section. IMPORTANT: THE "DefEnd" MUST BE THE LAST ENTRY IN THE
  226.     INIT IN ANY SITUATION OR THE STARTUP CODE MAY CRASH YOUR SYSTEM!
  227.     It's also needed if you don't want any libraries opened. Just set:
  228.  
  229. Init:    DefEnd
  230.  
  231.     and you're safe!
  232.  
  233. After the "DefEnd" macro, your program can start. You start with the label
  234. "Start".
  235.  
  236. You can also put the Init: label in the Startup.asm file if you always opens
  237. the same libraries etc.
  238.  
  239. Start:    ...do ya thang...
  240.  
  241.  
  242. You now have the argument pointer in A0 and the length in D0. Now you can have
  243. the arguments seperated even if you start from an icon. See the NextArg macro
  244. how this is done.
  245.  
  246. You don't need to preserve any registers on the stack. The startup code will
  247. do this for you. You must thow define a return code in D0 at the end of your
  248. program. This is now fixed for you by this macro:
  249.  
  250. End:    Return    0
  251.  
  252.  
  253. where 0 is the return code. This macro also takes a RTS so you don't have to
  254. think about that.
  255.  
  256.  
  257. NOTE: The startup code and the rest of your function code must be in the same
  258. section. If you want to change this you have to remove the PC relatives in the
  259. macros in the "Startup.asm" file. The PC-rel. are made with the purpose to
  260. make the assembled file smaller and faster.
  261.  
  262.  
  263. NOTE: If you use library versions bigger than 127, you have to alter the
  264. "Startup.asm" file in the macro "DefLib". Change the "moveq" to "move.l"
  265. (there is a little comment on that in the Startup.asm file).
  266.  
  267.  
  268.  
  269. HELPING MACROS
  270. ==============
  271.  
  272. 1)    "StartFrom",
  273.  
  274.     returns true or false. If false (0) then your program where started
  275.     from CLI else from Workbench:
  276.  
  277. ## Example:
  278.  
  279.     StartFrom
  280.     beq.b    .fromCli
  281.     ...
  282.  
  283.  
  284. 2)    "LibBase <library wo/ext>",
  285.  
  286.     gives you the library base in A6. Use it like this:
  287.  
  288. Start:    LibBase    dos
  289.     ...
  290.  
  291. 3)    "TaskName <"new task name">",
  292.  
  293.     will name your task with the name between the ""s. This macro is
  294.     optional, but useful to prevent more than one of this task to run.
  295.     You can use it at anytime in your code, but preferable as the first
  296.     thing in the init list. Remember the qvotes ("").
  297.  
  298. Init:    TaskName    "my_taskname"
  299.  
  300.     There seems to be a problem with DevPac and Barfly assemblers: you can
  301.     not use spaces between the qvotes. If you get problems with this then
  302.     use underscores.
  303.  
  304. 4)    "TaskPointer",
  305.  
  306.     will give you the task pointer to this task in d0. This macro does
  307.     no library calls and it's only using the d0 register. The pointer
  308.     to the task is stored internally in the startup code and processed
  309.     by a library call at main startup.
  310.  
  311. 5)    "TaskPri",
  312.  
  313.     sets your taskpri like this:
  314.  
  315. Init:    TaskPri    1
  316.  
  317. 6)    "Return",
  318.  
  319.     will put a return code in D0 and make a RTS. Use it like this:
  320.  
  321. End:    Return    0
  322.  
  323.     As you see, no need for RTS.
  324.  
  325.  
  326. See the Startup_example code to see how all this are done.
  327.  
  328.  
  329.  
  330. PARSING ARGUMENTS
  331. =================
  332.  
  333. You can of course read the argument string in a0 your self or by the ReadArgs()
  334. function, but I have implemented a macro which makes this very easy:
  335.  
  336.     "NextArg"
  337.  
  338. This macro read one argument from the argument string at a time. It cares
  339. about qvotes, tabs, spaces and asterix', so this one is good and fast!
  340.  
  341. You read an argument with "NextArg" and d0 points to the argument text which
  342. is also null-terminated. If there are no more args d0 will be NULL.
  343. You get one argument at the time (you seperate args in the CLI ny spaces etc).
  344.  
  345. In future this same macro will read tooltypes or icon arguments (if you
  346. started your task with a project icon which had your program as a default tool
  347. etc.)
  348.  
  349.  
  350. ## Example:
  351.  
  352. Start:    NextArg            ;get first/next arg
  353.     beq.w    ArgEnd        ;is (d0) null? then no more args
  354.  
  355.     move.l    d0,a0        ;use pointer
  356.     bsr.w    CheckArg    ;do something about it
  357.  
  358.     bra.b    Start        ;repeat
  359.  
  360. ArgEnd    ...            ;no more args, continue code...
  361.  
  362.  
  363. You don't have to worry about the registers used by NextArg. This is handled
  364. internally.
  365.  
  366.  
  367.  
  368. Special argument functions:
  369. ---------------------------
  370.  
  371. The argument parsing curently support 2 special situations:
  372.  
  373. 1) If you want to use quotes "" in your filename or argument
  374. 2) If you want to use newlines in your argument
  375.  
  376. Lets call our program "Test". If you then type this:
  377.  
  378. > test "This is a *"test*" to see qvotes *!"
  379.  
  380. it will output like this:
  381.  
  382.  
  383. This is a "test" to see qvotes *!
  384.  
  385.  
  386. or type this:
  387.  
  388. > test "This is a *"test*"*nto see qvotes *!"
  389.  
  390. it will output:
  391.  
  392.  
  393. This is a "test"
  394. to see qvotes *!
  395.  
  396.  
  397. The asterix symbol is the sequence start. There is no problem to add more
  398. functions if wanted, just let me know. The *! is added so you can see that you
  399. can use the asterix in any other combinations if you want it as a symbol.
  400.  
  401. This is also how you can do it with eg. the echo command.
  402.  
  403.  
  404.  
  405. SECTIONS
  406. ========
  407.  
  408. For those who use sections in their programs: you may have to edit the macros
  409. a little. This is because I have used (PC) relatives in my code to make it
  410. faster and smaller. Anyway, if you do get problems while using sections just
  411. remove all the (PC) in the macros. I don't think it should be necessary to
  412. remove any other (PC) since those are used internally in the startup code, but
  413. I haven't tried this yet so I don't know.
  414.  
  415.  
  416.  
  417. EXTRAS
  418. ======
  419.  
  420. In this archive you will also find another file called "Startup.i". This is
  421. just a very basic startup code which handles starts from Cli/Workbench. The
  422. only feature is that is allowing you to start your programs from icons. It
  423. does neither need any includes and it's consupt very little memory/place.
  424.  
  425. To use this file you only need the "Start" label.
  426.  
  427.     incdir    inc:
  428.     include    Startup.i
  429.  
  430. Start    movem.l    d0-a6,-(sp)        ;preserve registers
  431.  
  432.     ...your code...
  433.  
  434.     movem.l    (sp)+,d0-a6        ;put registers back
  435.     moveq    #0,d0            ;return code
  436.     rts
  437.  
  438.  
  439. In future I will expand this startup code so it may open devices as well, but
  440. that is just a thought. It will certantly get the argument feature added. The
  441. parse routine is finished, but I have to do some research on how to read the
  442. args. when started from a project icon for instant. Hm, if some of you guys/
  443. girls has some info about that, then please let me know. I also need some
  444. info on how to self-detatch the code from eg. the cli. The cli argument
  445. parsing is finished thow (see "NextArg").
  446.  
  447.  
  448.  
  449. SUMMARY
  450. =======
  451.  
  452. Macros:
  453.  
  454. DefEnd        - Sets end of Init: section. *** ALWAYS REQUIRED *** !
  455. DefLib        - Defines the library name and version you want opened.
  456. Version        - Init a version string to your binary.
  457. TaskName    - Names your task (use underscores if any trouble occure).
  458. TaskPri        - Sets your task to a task priority (system safe).
  459.  
  460. NextArg        - D0 points to an extracted nullterminated argument.
  461. LibBase        - Gives you the library base you ask for, in A6.
  462. StartFrom    - Tells you if your program where started from CLI or WB.
  463. TaskPointer    - Gives you the pointer to this taskstructure.
  464. Return        - Gives a return code and exits.
  465.  
  466.  
  467.  
  468. TROUBLE SHOOTING
  469. ================
  470.  
  471. DefLib
  472.     You use lot of libraries (more than 17) and the machine crashes.
  473.  
  474.     SOLV: Edit the Startup.asm file and set the "zyxMax =" to a higher
  475.     number. This buffer will be allocated (def: 204 bytes) by AllocMem().
  476.  
  477. Version
  478.     You get assembler errors all the time about missing qvotes or similar.
  479.  
  480.     SOLV: Some assemblers (like DevPac and Barfly) doesn't tolerate spaces
  481.     in macro arguments. In these cases it's smart not to use this macro.
  482.     Edit a version string into your source manually (this is now default
  483.     from NewStartup35.lha).    The "Version" suits for the version string to
  484.     accompany the assembled program. With AsmOne this macro should not be
  485.     a problem.
  486.  
  487. TaskName
  488.     You get the same problem as with the Version macro (see above).
  489.  
  490.     SOLV: Use underscores instead of spaces or compress the name like eg.:
  491.     You want "My task", then use "My_task" or "MyTask" instead.
  492.  
  493.  
  494.  
  495. If you find any bugs or have any decissions to come with, do not hasitate to
  496. write me.
  497.  
  498.     e-mail: kenneth@norconnect.no
  499.  
  500.     Digital Surface
  501.     Attn: Kenneth C. Nilsen
  502.     Kvernhusrenen 31
  503.     N-5227 S-Neset
  504.  
  505.     (Norway).
  506.  
  507.  
  508. So, good luck and may your program work for ever! :)
  509.  
  510. ------------------------------------------------------------------------------
  511. Source header example:
  512. ------------------------------------------------------------------------------
  513.  
  514. Startskip    =    0    ;0=WB/CLI, 1=CLI only
  515. Processor    =    0    ;0 or 680x0
  516. MathProc    =    0    ;0 or 6888x/68040
  517.  
  518.     Incdir    "Includes:"
  519.     Include    "Startup.asm"
  520.  
  521. Init:    DefEnd
  522.  
  523. Start:
  524.  
  525. Close:    Return    0
  526.  
  527. ------------------------------------------------------------------------------
  528. This is all you need to get the startup code work!
  529. See the example source on how to take advantage of the features.
  530. ------------------------------------------------------------------------------
  531.